Java 3D API Specification

C H A P T E R11

A Java 3D application running on a particular machine could have one of several options available to it for playing the audio image created by the sound renderer. Perhaps the machine Java 3D is executing on has more than one sound card (e.g., one that is a Wave Table Synthesis card and the other with accelerated sound spatialization hardware). Furthermore, suppose there are Java 3D audio device drivers that execute Java 3D audio methods on each of these specific cards. In such a case the application would have at least two audio device drivers through which the audio could be produced. For such a case the Java 3D application must choose the audio device driver with which sound rendering is to be performed. Once this audio device is chosen, the application can additionally select the type of audio playback type the rendered sound image is to be output on. The playback device (headphones or speaker(s)) is physically connected to the port the selected device driver outputs to.

11.1 AudioDevice Interface

The selection of this device driver is done through methods in the PhysicalEnvironment object - see Section C.9, "The PhysicalEnvironment Object." The application would query how many audio devices are available. For each device, the user can get the AudioDevice object that describes it and query its characteristics. Once a decision is made about which of the available audio devices to use for a PhysicalEnvironment, the particular device is set into this PhysicalEnvironment's fields. Each PhysicalEnvironment object may use only a single audio device.

The AudioDevice object interface specifies an abstract input device that creators of Java3D class libraries would implement for a particular device. Java 3D's uses several methods to interact with specific devices. Since all audio devices implement this consistent interface, the user could have a portable means of initialize, set particular audio device elements and query generic characteristics for any audio device.

Constants

public final static int HEADPHONES

Specifies that the audio playback will be through stereo headphones.

public final static int MONO_SPEAKER

Specifies that the audio playback will be through a single speaker some distance away from the listener.

public final static int STEREO_SPEAKERS

Specifies that the audio playback will be through stereo speakers some distance away from, and at some angle to the listener.

Constructors

The AudioDevice object (part of an implementation of the AudioDevice interface) specifies the following constructor.

public AudioDevice()

Constructs and initializes a new AudioDevice object with the following fields:

Audio playback type: HEADPHONES
Distance from listener to speaker(s): 0.0
Angle offset of speaker(s): 0.0

11.1.1 Initialization

Each audio device driver must be initialized. The chosen device driver should be initialized before any Java 3D Sound methods are executed because the implementation of the Sound methods, in general, are potentially device driver dependent.

Methods

public abstract boolean initialize()

Initialize the audio device. Exactly what occurs during initialization is implementation dependent. This method provides explicit control by the user over when this initialization occurs.

public abstract boolean close()

Closes the audio device, releasing resources associated with this device

11.1.2 Audio Playback

Methods to set and retrieve the audio playback parameters are part of the AudioDevice object. The audio playback information specifies that playback will be through:

• Stereo headphones.

• A monaural speaker.

• A pair of speakers, equally distant from the listener, both at some angle from the head coordinate system Z axis. It's assumed that the speakers are at the same elevation and oriented symmetrically about the listener.

The type of playback chosen affects the sound image generated. Cross-talk cancellation is applied to the audio image if playback over stereo speakers is selected.

Methods

The following methods affect the audio playback of sound processed by Java 3D sound renderer.

public abstract void setAudioPlaybackType(int type)
public abstract int getAudioPlaybackType()

These methods set and retrieve the type of audio playback device (HEADPHONES, MONO_SPEAKER, or STEREO_SPEAKERS) used to output the analog audio from rendering Java 3D Sound nodes.

public abstract void setCenterEarToSpeaker(float distance)
public abstract float getCenterEarToSpeaker()

These methods set and retrieve the distance in meters from the center ear (the midpoint between the left and right ears) and one of the speakers in the listener's environment. For monaural speaker playback, a typical distance from the listener to the speaker in a workstation cabinet is 0.76 meters. For stereo speakers placed at the sides of the display, this might be 0.82 meters.

public abstract void setAngleOffsetToSpeaker(float angle)
public abstract float getAngleOffsetToSpeaker()

These methods set and retrieve the angle in radians between the vectors from the center ear to each of the speaker transducers and the vectors from the center ear parallel to the head coordinate's Z axis. Speakers placed at the sides of the computer display typically range between 0.28 to 0.35 radians (between 10 and 20 degrees).

11.1.3 Device Driver Specific Data

While the sound image created for final output to the playback system is either only mono or stereo (for this version of Java 3D) most device driver implementations will mix the left and right image signals generated for each rendered sound source before outputting the final playback image. Each sound source will use N input channels of this internal mixer. Each implemented Java 3D audio device driver will have its own limitations and driver-specific characteristics. These include channel availability and usage (during rendering). Methods for querying these device-driver specific characteristics are provided below.

Methods

public abstract int getTotalChannels()

Maximum number of channels available for Java 3D sound rendering for all sound sources.

public abstract int getChannelsAvailable()

During rendering, when sound nodes are playing, this method returns the number of channels still available to Java 3D for rendering additional sound nodes.

public abstract int getChannelsUsedForSound(Sound node)

Each particular Sound node will require use of some number of channels when rendered. This method returns the number of channels needed to render a particular Sound node. The return value of this method is the same no matter if the Sound node is currently active and enabled (being rendered) or if it is inactive.

11.2 Instantiating and Registering a New Device

A browser or applications developer must instantiate whatever system-specific audio devices that he or she needs and that exist on the system. This device information typically exists in a site configuration file. The browser or application will instantiate the physical environment as requested by the end-user.

The API for instantiating devices is site-specific, but it consists of a device object with a constructor and at least all of the methods specified in the AudioDevice interface.

Once instantiated, the browser or application must register the device with the Java 3D sound scheduler by associating this device with a PhysicalEnvironment. The setAudioDevice method introduces new devices to the Java 3D environment and the allAudioDevices method produces an enumeration that allows examining all available devices within a Java 3D environment See Section C.9, "The PhysicalEnvironment Object," for more details,

---

Java 3D API Specification

Copyright © 1997, Sun Microsystems, Inc. All rights reserved.